Skip to content

fix: improve error messages for platform credential expiry in Semantic Layer tools#714

Open
psaikaushik wants to merge 3 commits into
dbt-labs:mainfrom
psaikaushik:fix/670-platform-credential-error-message
Open

fix: improve error messages for platform credential expiry in Semantic Layer tools#714
psaikaushik wants to merge 3 commits into
dbt-labs:mainfrom
psaikaushik:fix/670-platform-credential-error-message

Conversation

@psaikaushik
Copy link
Copy Markdown
Contributor

@psaikaushik psaikaushik commented Apr 12, 2026 •
edited
Loading

Summary

When query_metrics or execute_sql fail due to expired dbt Cloud platform credentials, the error message currently points users toward local Snowflake re-authentication steps — which is misleading and sends them down the wrong troubleshooting path.

This PR adds detection for platform credential expiry errors and appends a clear, actionable hint directing users to refresh their credentials in the dbt Cloud UI.

Closes #670

What Changed

src/dbt_mcp/semantic_layer/client.py

  • Added _PLATFORM_CREDENTIAL_ERROR_PATTERNS — a list of compiled regex patterns that match common credential expiry messages from Snowflake/data platforms (SSO expired, OAuth token expired, etc.)
  • Added _PLATFORM_CREDENTIAL_HINT — a clear, actionable message explaining this is a platform-side credential issue and directing users to dbt Cloud UI → Profile → Credentials
  • Added _is_platform_credential_error() — a helper that checks an error string against all known patterns
  • Updated _format_semantic_layer_error() — now detects platform credential errors and appends the hint, while preserving the original error message and all existing formatting behavior

tests/unit/semantic_layer/test_platform_credential_errors.py

  • 10 tests for _is_platform_credential_error() — covers all known patterns, case insensitivity, and negative cases (generic errors, syntax errors, timeouts, empty strings)
  • 5 tests for _format_semantic_layer_error() — verifies the hint is appended for credential errors, preserved for QueryFailedError wrappers, and not added for generic errors

Why

Users on dbt Cloud with Snowflake SSO credentials that expire see this error:

SSO authentication has expired, please re-connect to Snowflake:
https://docs.getdbt.com/faqs/Troubleshooting/refresh-snowflake-oauth-credentials

This sends them to local re-authentication docs, which doesn't fix the problem. The actual fix is to refresh development credentials in the dbt Cloud UI. This PR makes that distinction clear.

Test plan

  • All new unit tests pass (15 tests)
  • No changes to existing test behavior — the original _format_semantic_layer_error logic is untouched; the hint is additive
  • Manual verification with expired Snowflake credentials on dbt Cloud

Checklist

  • I have performed a self-review of my code
  • I have added tests that prove my fix is effective
  • New and existing unit tests pass locally with my changes
  • Changelog entry added

@psaikaushik psaikaushik requested review from a team, b-per, jairus-m and jasnonaz as code owners April 12, 2026 21:34
@psaikaushik psaikaushik mentioned this pull request Apr 12, 2026
Open
@psaikaushik
Copy link
Copy Markdown
Contributor Author

psaikaushik commented Apr 15, 2026

@jairus-m thanks for merging #715! When you get a chance, this one is ready for review as well. Just rebased it onto latest main. Let me know if anything needs changing.

@jairus-m
Copy link
Copy Markdown
Collaborator

jairus-m commented Apr 15, 2026

@psaikaushik hello pls make sure to address the same baseline comments I made from your other PR - signed commits, change log issue, etc. In the meantime as well, would love to see validation / screenshots of your fixes! (before and after as this update ). That would be very helpful 🙏

@psaikaushik psaikaushik force-pushed the fix/670-platform-credential-error-message branch from 18a49c5 to 6c4ae85 Compare April 15, 2026 22:14
@psaikaushik
Copy link
Copy Markdown
Contributor Author

psaikaushik commented Apr 16, 2026

@jairus-m : Just created another commit fixing all of them. Sorry about that. It skipped my mind. Thanks for your help! Regarding the test, I mocked the credentials expiration

Before

SSO authentication has expired, please re-connect to Snowflake: https://docs.getdbt.com/faqs/Troubleshooting/refresh-snowflake-oauth-credentials

After

SSO authentication has expired, please re-connect to Snowflake: https://docs.getdbt.com/faqs/Troubleshooting/refresh-snowflake-oauth-credentials

Hint: This error indicates that your dbt Cloud development credentials have expired. This is a dbt Cloud platform credential issue, not a local authentication problem.
To fix this, go to the dbt Cloud UI → Profile → Credentials and refresh your development environment credentials for the relevant project.
See: https://docs.getdbt.com/docs/dbt-cloud-environments/develop-in-the-cloud#access-the-cloud-ide

Please take a look. thanks!

@psaikaushik
Copy link
Copy Markdown
Contributor Author

psaikaushik commented Apr 17, 2026

@jairus-m : Gentle reminder on the review. All the comments are addressed. Please take a look whenever you are free. thanks!

@jairus-m
Copy link
Copy Markdown
Collaborator

jairus-m commented Apr 17, 2026

Hey @psaikaushik totally, thank you for the friendly reminder. I have this PR in mind and it's absolutely in my "todo" queue. As you know, plates get full - thank you for your patience. 🙏 Pls hang tight.

@jairus-m
Copy link
Copy Markdown
Collaborator

jairus-m commented Apr 20, 2026

Hey @psaikaushik I'm trying to checkout your branch and merge the latest changes from main. There are conflicts. I'm trying to make changes but I do not think you allow maintainers to edit your branch.

Can you update your branch and address the conflicts? Or allow me to push the merge to main?

Screenshot 2026-04-20 at 1 45 16 PM

@psaikaushik
Copy link
Copy Markdown
Contributor Author

psaikaushik commented Apr 20, 2026

Hey @psaikaushik I'm trying to checkout your branch and merge the latest changes from main. There are conflicts. I'm trying to make changes but I do not think you allow maintainers to edit your branch.

Can you update your branch and address the conflicts? Or allow me to push the merge to main?

Screenshot 2026-04-20 at 1 45 16 PM

@jairus-m : Sorry about that. Just gave permissions on the PR to be editable by the maintainers. I am also trying to rebase on my side but did that so that it's easier for you. Please take a look. thanks!

@psaikaushik
fix: improve error messages for platform credential expiry in Semanti…
6ffb4bd 
…c Layer tools

When query_metrics or execute_sql fail due to expired dbt Cloud platform
credentials, the error now clearly indicates this is a platform-side issue
and directs users to refresh credentials in the dbt Cloud UI, rather than
suggesting local Snowflake re-authentication.

Closes dbt-labs#670
@psaikaushik
chore: fix changie entry kind from Fixed to Bug Fix for issue 670
bf4c678
@psaikaushik
fix: apply ruff formatting and fix QueryFailedError signature in tests
8c6c4ff
@psaikaushik psaikaushik force-pushed the fix/670-platform-credential-error-message branch from f70b032 to 8c6c4ff Compare April 20, 2026 21:06
jairus-m
jairus-m reviewed Apr 21, 2026
View reviewed changes
Comment thread src/dbt_mcp/semantic_layer/client.py
Comment on lines +45 to +52
_PLATFORM_CREDENTIAL_ERROR_PATTERNS: list[re.Pattern[str]] = [
re.compile(r"SSO authentication has expired", re.IGNORECASE),
re.compile(r"re-connect to Snowflake", re.IGNORECASE),
re.compile(r"refresh.snowflake.oauth.credentials", re.IGNORECASE),
re.compile(r"authentication token has expired", re.IGNORECASE),
re.compile(r"oauth.*token.*expired", re.IGNORECASE),
re.compile(r"token.*expired.*re-?authenticate", re.IGNORECASE),
]
Copy link
Copy Markdown
Collaborator

@jairus-m jairus-m Apr 21, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Left a comment related to these lines in the issue. Let me know what you think! We can continue that convo there for now.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@jairus-m jairus-m jairus-m left review comments

@jasnonaz jasnonaz Awaiting requested review from jasnonaz jasnonaz is a code owner

@b-per b-per Awaiting requested review from b-per b-per is a code owner

At least 1 approving review is required to merge this pull request.

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

Semantic Layer / execute_sql tools fail with unhelpful error when dbt platform's Snowflake credentials expire

2 participants

@psaikaushik @jairus-m